/* Foley C# Utilities
 * Copyright (C)2002 Rodney S. Foley
 *  
 * This program is free software; you can 
 * redistribute it and/or modify it under the 
 * terms of the GNU General Public License as 
 * published by the Free Software Foundation; 
 * either version 2 of the License, or (at your 
 * option) any later version.
 * 
 * This program is distributed in the hope that 
 * it will be useful, but WITHOUT ANY WARRANTY; 
 * without even the implied warranty of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR 
 * PURPOSE. See the GNU General Public License 
 * for more details.
 * 
 * You should have received a copy of the GNU 
 * General Public License along with this 
 * program; if not, write to: 
 * 
 *		Free Software Foundation, Inc., 
 *		59 Temple Place, Suite 330, 
 *		Boston, MA 02111-1307 USA
 * 
 *					- or -
 * 
 * http://opensource.org/licenses/gpl-license.php
 */

using System;
using System.Collections;

namespace Foley.Utilities.Collections
{
	/// <summary>
	/// Represents an enhanced version of the ICollection interface.
	/// </summary>
	/// <remarks>
	/// <para>
	/// This class is an initial attempt to try to correct how Microsoft
	/// defines a collection.  Some of the methods in IList really belong 
	/// in ICollection, since all collections can share these methods and
	/// properties, from lists, to sets, to maps.  
	/// </para>
	/// <see cref="ICollection"/> implementations fall into three categories: 
	/// read-only, fixed-size, variable-size. A read-only <see cref="ICollection"/> 
	/// cannot be modified.  A fixed-size <see cref="ICollection"/> does not 
	/// allow the addition or removal of elements, but it allows the modification 
	/// of existing elements. A variable-size <see cref="ICollection"/> allows 
	/// the addition, removal and modification of elements.
	/// </remarks>
	public interface ICollection2 : ICollection
	{
		/// <summary>
		/// When implemented by a class, gets a <c>value</c>
		/// idicating whether the collection is empty or not.
		/// </summary>
		/// <value>
		/// <c>true</c> if the collection contains no elements; otherwise, 
		/// <c>false</c>.
		/// </value>
		bool IsEmpty { get; }

		/// <summary>
		/// When implemented by a class, gets a <c>value</c> 
		/// indicating whether the collection has a fixed size.
		/// </summary>
		/// <value>
		/// <c>true</c> if the collection has a fixed size; otherwise, 
		/// <c>false</c>.  The default should be <c>false</c>.
		/// </value>
		/// <remarks>
		/// A collection with a fixed size does not allow the 
		/// addition or removal of elements after the collection 
		/// is created, but it allows the modification of existing elements.
		/// </remarks>
		bool IsFixedSize {get;}

		/// <summary>
		/// When implemented by a class, gets a <c>value</c> 
		/// indicating whether the collection is read-only.
		/// </summary>
		/// <value>
		/// <c>true</c> if the collection is read-only; otherwise, 
		/// <c>false</c>.  The default should be <c>false</c>.
		/// </value>
		/// <remarks>
		/// A collection that is read-only does not allow the 
		/// addition, removal, or modification of elements 
		/// after the collection is created.
		/// </remarks>
		bool IsReadOnly {get;}

		/// <summary>
		/// When implemented by a class, removes all items from the collection.
		/// </summary>
		/// <exception cref="NotSupportedException">
		/// The collection is read-only.
		/// </exception>
		/// <remarks>
		/// Implementations of this method can vary in how they handle 
		/// the <see cref="ICollection.Count"/> and the capacity of a 
		/// collection.  Typically, the count is set to zero. The capacity 
		/// can be set to zero or a default <c>value</c>, or it can remain 
		/// unchanged.
		/// </remarks>
		void Clear();
	}
}
